<h1>The Structure of a Controller</h1>
<p>Within the Trongate framework, controllers are PHP classes that extend the built-in <a href="documentation-ref/list_refs/class_reference/the-trongate-class">Trongate class</a>. Extending this foundational class provides controllers with immediate access to all of Trongate's core functionalities, such as form validation, database interactions, URL helpers, and more, enabling them to efficiently manage application logic and user interactions.</p>

<h2>Naming Conventions</h2>
<p>It is crucial to adhere to the following naming conventions when working with Trongate controllers:</p>
<ol>
    <li><strong>File Naming:</strong> Controller file names should start with a capital letter, reflecting their importance and usage within the module.</li>
    <li><strong>Class Naming:</strong> Similarly, controller class names should begin with a capital letter, aligning with PHP's best practices for class definitions.</li>
    <li><strong>Module Naming:</strong> The controller class name should correspond to the name of its module, which can be in all lowercase. This consistency aids in maintaining a clear and logical structure within the project.</li>
</ol>

<h2>Example: The Dice Controller</h2>
<p>Below is an example of a simple Trongate controller file named 'Dice.php', located within a hypothetical module named 'dice'. This example demonstrates how a controller can encapsulate specific functionalities:</p>
[code=php]
&lt;?php
class Dice extends Trongate {

    function roll() {
        $number = rand(1, 6);
        echo $number;
    }
    
}
[/code]

<h2>Detailed Breakdown of the Dice Controller</h2>
<p>The 'Dice' controller provides a demonstration of how controllers are structured and function within the Trongate framework. Let's examine each component of the controller:</p>

<h3>PHP Opening Tag</h3>
[code=php]&lt;?php[/code]
<p>This is the opening tag for any PHP script. It tells the server that the code following this tag should be interpreted as PHP code.</p>

<h3>Class Declaration</h3>
[code=php]class Dice extends Trongate {[/code]
<p>This line declares a new class named 'Dice' which extends the 'Trongate' class. Extending a class in PHP is a fundamental aspect of object-oriented programming that allows the 'Dice' class to inherit all methods and properties of the Trongate framework's base class.</p>

<h3>Function Declaration</h3>
[code=php]function roll() {[/code]
<p>The code above is the first line of a method named 'roll' within the Dice class. Methods are functions that are defined inside a class and describe the behaviors or capabilities of objects created from the class. In Trongate, as in many MVC frameworks, these methods can be linked to specific routes (URLs).</p>
<div class="alert alert-info">
    <strong>Note:</strong> For brevity, the example provided omits elements such as type hinting, return types, visibility modifiers (public, private, protected), and doc blocks. These are essential for production code to ensure clarity, type safety, and proper documentation. For additional information on this topic, please refer to the Trongate framework's <a href="documentation/display/php_framework/basic-concepts/regarding-coding-style" target="_blank">coding style guide</a>.
</div>

<h3>Method Functionality</h3>
<p>Within the curly braces of the <code>roll()</code> method, we have this line of code:</p>
[code=php]$number = rand(1, 6);[/code]
<p>The above line of code generates random number between 1 and 6 and assigns to the variable, <code>$number</code>.</p>

<div class="alert alert-info">
    <p>The <code>rand()</code> function is a built-in PHP function used to generate random numbers.</p>
</div>

<p>Moving on, the next line of code - within the <code>roll()</code> method is as follows:</p>
[code=php]echo $number;[/code]
<p>This line outputs the value of <code>$number</code> to the webpage. In the context of a controller within a framework like Trongate, this typically means sending the data back to the client's browser where it can be rendered as part of the HTML or handled via JavaScript.</p>

<h3>Class and Method Closure</h3>
<p>Finally, the <code>roll()</code> method is closed with a closing curly bracket:</p>
[code=php]}[/code]

<div class="alert alert-info">In PHP, as in many other programming languages, curly braces are used to define the scope of classes, methods, and other control structures, ensuring that the code enclosed within them is associated with that specific class or method.</div>
<p>This breakdown highlights how the 'Dice' controller leverages both <a href="documentation/reference" target="_blank">Trongate's</a> and PHP's built-in functionalities to perform its tasks, generating a random number between one and six.</p>

<h2>Accessing the Controller</h2>
<p>The <code>roll()</code> method can be invoked by navigating to the following URL:</p>
<code class="php">http://example.com/dice/roll</code>

<p>This URL structure would cause the 'roll' method to be invoked, generating a random number between one and six using PHP's inbuilt rand() function. The random number that has been generated would then be displayed on the screen.</p>
<div class="text-center">
    <figure>
        <img src="images/73/roll_theZzyt.png" alt="Sample output" style="width:100%">
        <figcaption>Sample browser output (zoomed in for clarity)</figcaption>
    </figure>
</div>

<h2>URL Mapping and Routing</h2>
<p>The URL provided adheres to Trongate's <a href="documentation/display/php_framework/understanding-routing/automatic-url-routing" target="_blank">rules for automatic URL routing</a>. In the example above:</p>
<ul>
    <li>The first URL segment, <code>dice</code>, maps to a class named 'Dice'. This class is part of a module also named 'dice'.</li>
    <li>The second URL segment, <code>roll</code>, specifies the method to be invoked. Thus, it triggers the <code>roll()</code> method within the loaded Dice class.</li>
</ul>
<p>This structured URL pattern ensures that requests are routed efficiently to the appropriate controller actions, making URL management straightforward and intuitive within the Trongate framework.</p>